Skip to content

fix(docs): repair remaining prose definitions, invariant titles, and comment fragments from #9072 - #9166

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/fix-9072-tail-20261121
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/fix-9072-tail-20261121

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Goal And Delivered Outcome

  • Outcome basis / optional anchor: Follow-up cleanup for PR #9072 (62784ecc532585d4f277dd94fe9a169fb95b5050) and PR #9079 (a05425b576dafca2ba16105f796672ec89c07bfb).
  • Goal/source and gap: After PR #9079 restored the P1 prompt-injection/review-contract prohibitions and broken sentence fragments from #9072, a residual set of #9072 clause-trimming artifacts remained on main: (1) positive explanations after colons and causal links were trimmed along with preceding not / 而不是 phrases (e.g. loopx/capabilities/explore/README.zh-CN.md, loopx/capabilities/reliability_diagnostics/README.zh-CN.md, docs/development/testing-and-quality.md); (2) non-redundant authority boundaries and pronoun antecedents were dropped (loopx/capabilities/manager_context/README.md, loopx/capabilities/reward_memory/README*.md, docs/development/testing-and-quality.md, docs/development/control-plane-course/*, loopx/capabilities/issue_fix/docs/state-kernel-domain-state-case-study.zh-CN.md); (3) the non-blocking P2 operational rule in docs/book/en/chapters/00-reading-guide.md (Record preview, execution, readback, and test results separately.) plus 12 Dev Book ## Invariants bold summary lead-ins and named Boundary / Failure titles (06-codex-app.md, core-state-machines.md, 08-extension-placement.md, source-protocol-map.md, source-trace-protocol-chain.md, source-validation-to-pr.md, 01-from-session-to-loop.md, 04b-budget-and-admission.md, 09-extension-scaffold.md) were stripped when their titles contained negative words; and (4) dangling semicolons, empty JSDoc lines (* */), and orphan 1-word docstring lines remained in 10 TypeScript/Python comments.
  • Observable before → after, with the validation row that proves it:
    • Before (2b6dfe0a70892289f42fc260616545cf7ad0b1db): examples/dev-book-publication-smoke.py had no structural check for ## Invariants bold lead-ins or Cost/Boundary/Failure ordinal sequences, docs/book/en/chapters/00-reading-guide.md omitted the separate-recording requirement retained in Chinese, capability/testing docs carried truncated colon definitions or false/half premises (字段、命令、枚举和合法结果未变。, --note 被 parser 接受或出现在成功响应中。), and TS/Python comments retained * */ and trailing ;.
    • After (d3f9c9b8a667117849abb2ff83b8b1d5781bfb82): all positive definitions, non-authority boundaries, antecedent clauses, bilingual reading-guide parity, Dev Book bold Invariant/Boundary/Failure titles, and code comment punctuation are restored without bringing back redundant rhetorical contrasts; examples/dev-book-publication-smoke.py and tests/test_dev_book_reader_checkpoints.py enforce contiguous ## Invariants bold lead-ins, contiguous Cost/Boundary/Failure titles, and 00-reading-guide.md bilingual parity (proven by counterfactual failure against 2b6dfe0a70 and 290 passed unit tests + 7/7 TS and 3/3 Python comment-stripped AST identity).
  • Issue/task and intended base: Related to Remove redundant defensive prose from prompts and comments #9072, Related to fix: restore P1 safety prohibitions and broken prose from #9072 #9079; intended base main (2b6dfe0a70892289f42fc260616545cf7ad0b1db).

Author Declaration

  • Written by: model_agent (Gemini family, Google)

Implemented against

  • Specification and revision: AGENTS.md (#evidence-based-budget-decisions, #smoke-retention-policy) and examples/dev-book-publication-smoke.py at 2b6dfe0a70892289f42fc260616545cf7ad0b1db, plus the review frame recorded on PR #9072 and PR #9072 post-merge audit.
  • Criteria:
Criterion (spec clause) Disposition Symbol / path Test or command
Preserve positive definitions, causal explanations, and non-redundant authority/equivalence clauses during prose compaction (AGENTS.md#evidence-based-budget-decisions) implemented loopx/capabilities/explore/README.zh-CN.md, loopx/capabilities/manager_context/README.md, loopx/capabilities/reliability_diagnostics/README.zh-CN.md, loopx/capabilities/reward_memory/README*.md, docs/development/testing-and-quality.md python3 examples/capability-extension-placement-doc-smoke.py, git diff --check
Restore bilingual 00-reading-guide.md separate-recording rule and stripped Dev Book ## Invariants / Boundary / Failure bold lead-ins & truncated sentences (PR #9072 review frame) implemented docs/book/en/chapters/00-reading-guide.md, docs/book/chapters/*.md, docs/book/en/chapters/*.md, examples/dev-book-publication-smoke.py::assert_chapter_invariants_and_sequences python3 examples/dev-book-publication-smoke.py, python -m pytest -q tests/test_dev_book_reader_checkpoints.py
Repair dangling comment semicolons, empty JSDoc lines, and orphan single-word docstring lines without altering runtime AST implemented loopx/control_plane/**/*.ts, apps/presentation/dashboard/src/data/workspace-progressive-status.ts, packages/loopx-codex-provider-routing/src/loopx_codex_provider_routing/openai_policy.ts, loopx/extensions/lark/private_ingress.py, loopx/capabilities/native_chat/*.py npm run -s typecheck:control-plane, focused TS/Python suites, comment-stripped AST parity check
  • Self-check before submission: Read AGENTS.md, CLAUDE.md, CONTRIBUTING.md, .github/CODEOWNERS, pyproject.toml, package.json, setup.py, and examples/dev-book-publication-smoke.py; audited the full #9072 diff (27eaeb1277..62784ecc53) against current origin/main (2b6dfe0a70) after #9079; deliberately kept loopx/control_plane/heartbeat/bootstrap_prompt.py _matches_published_bootstrap unchanged so wrappers upgraded since #9072 remain recognized alongside historical wrappers without another loader byte churn; verified 100% comment/docstring-stripped AST parity on all 7 touched .ts files and 3 touched product .py files.

Scope And Continuation

  • Completed scope and remaining work: Complete within this scope. Restores the remaining #9072 prose/comment truncation tail and adds durable Dev Book structural invariant/sequence and bilingual reading-guide checks.
  • Slice boundary / successor: N/A — self-contained maintenance completion for the remaining #9072 tail; bootstrap_prompt.py compatibility matching stays intentionally in place for already-published v2 wrappers.

Validation

  • Tested revision: d3f9c9b8a667117849abb2ff83b8b1d5781bfb82
  • Run state: finished
  • Input classes: synthetic, public_fixture
Check kind Result Public-safe evidence / limitation
unit passed python -m pytest -q tests/test_dev_book_reader_checkpoints.py tests/test_repository_instruction_delivery.py tests/test_skill_delivery_parity.py tests/test_lark_private_ingress.py tests/test_antigravity_steward_adapter.py tests/test_native_steward_managed_mode.py (290 passed, 336 subtests passed), including negative truncation guards in ReaderCheckpointGuardTests::test_chapter_invariant_and_sequence_guards_reject_truncation.
unit passed node --experimental-strip-types --test across touched control-plane TS suites (conversation_binding, source_grants, receipt_log_snapshot, refresh_recovery, task_lease_eligibility), packages/loopx-codex-provider-routing/tests/*.test.ts, and apps/presentation/dashboard/src/data/conversation-returns.test.mjs (113 + conversation-returns passed, 0 failed).
static passed npm run -s typecheck:control-plane, python -m ruff check on all 5 touched Python files, python -m mypy (17 strict files), python scripts/check_rfc_bilingual.py --base origin/main --head HEAD, git diff --check, python scripts/generate_semantic_inventory.py --changed-from origin/main (0 new vocabulary candidates), and loopx check on all 39 changed paths (ok: true, errors: []).
regression_parity passed python3 examples/dev-book-publication-smoke.py, python3 examples/capability-extension-placement-doc-smoke.py, and python3 examples/pr-review-command-smoke.py all pass on d3f9c9b8a6; counterfactual execution of assert_chapter_invariants_and_sequences and 00-reading-guide.md bilingual check against 2b6dfe0a70 (origin/main) fails on the exact missing bold lead-ins and missing English operational clause; TypeScript removeComments printer (7/7) and Python docstring-stripped ast.dump (3/3) are byte-for-byte identical between 2b6dfe0a70 and d3f9c9b8a6.
integration passed loopx canary premerge --from-git-diff --git-diff-base origin/main and loopx change-quality verify on d3f9c9b8a6.
  • Coverage and gaps: All 39 changed files are covered by Dev Book publication/checkpoint smokes, comment/docstring-stripped AST equivalence checks, TypeScript/Python static checks, and focused runtime unit tests. Rendered MkDocs HTML site build (--site-dir) and remote GitHub Actions CI were not consulted locally.

See validation disclosure guidance.

Frontend / Visual Evidence

  • UI impact: none
  • Before: N/A (apps/presentation/dashboard/src/data/workspace-progressive-status.ts has a JSDoc comment-only edit; TypeScript removeComments AST output is identical to origin/main).
  • After: N/A
  • First viewport and preview: N/A
  • States and viewports shown: N/A
  • Source data: none
  • Attention review: N/A
  • Craft review: N/A

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Refactoring (no functional changes)
  • Documentation update
  • Test update

LoopX Area

  • Control plane (goals, todos, quota, scheduler, registry, runtime)
  • Benchmark boundary (adapters, runners, verifiers, scoring, evidence)
  • Capability or extension (providers, adapters, skills)
  • Public docs or presentation surface (README, protocols, dashboard)
  • Build, packaging, installer, or CI
  • Host or runtime integration

Technical Direction

  • Direction / acceptance reference, when applicable: Core documentation, capability contract, and Dev Book structural integrity follow-up to #9072 / #9079.

Shared-authority RFC fixture impact

  • Production-scale fixture schema: N/A
  • Semantic dimensions changed, or reviewed no-impact rationale: N/A (comment-only changes in .ts/.py product modules; zero runtime AST or protocol changes).
  • Provider conformance arms run: N/A
  • Read-only legacy/file/PostgreSQL three-arm rehearsal (required for promotion, runtime-routing, or compatibility-projection changes): N/A

Boundary Checklist

  • Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths (including .loopx/, .codex/goals/, and live ACTIVE_GOAL_STATE.md).
  • I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
  • I kept the change scoped to the linked issue/task.
  • Existing English/Chinese RFC pairs (including ledger entries) both have a diff, and the local premerge check python3 scripts/check_rfc_bilingual.py --base origin/main --head HEAD passes, or no paired RFC changed.
  • I completed the visual evidence section for UI changes, or marked UI impact none.
  • Every commit includes a DCO Signed-off-by trailer (git commit -s).

…comment fragments from #9072

Restore over-trimmed positive colon definitions, non-authority boundaries, antecedent clauses, stripped Dev Book bold Invariant/Boundary/Failure titles, bilingual reading-guide parity, and dangling comment/docstring punctuation left behind after PR #9072 and PR #9079. Add structural Invariants and named-sequence checks to examples/dev-book-publication-smoke.py and tests/test_dev_book_reader_checkpoints.py.

Signed-off-by: LoopX Agent <[email protected]>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

Reviewer: model_agent (declared_model=Gemini, declared_provider=Google, declaration_source=self_reported)
Target exact head: 9166@d3f9c9b8a667117849abb2ff83b8b1d5781bfb82

动机

  • Affected caller or operator: Contributors, reviewers, and readers relying on Dev Book chapters, capability docs, and source comments.
  • Before/after scenario: Before: 00-reading-guide.md lacked the separate-recording rule, 12 Dev Book Invariants/Cost/Boundary/Failure headings lost bold lead-in titles, and dev-book-publication-smoke.py could not catch regressions. After: all prose definitions, titles, and comments are restored with structural enforcement.
  • Observable outcome: dev-book-publication-smoke.py passed, capability-extension-placement-doc-smoke.py passed, test_dev_book_reader_checkpoints.py passed (20 passed, 336 subtests), conversation_binding.test.ts passed, and canary premerge quick passed (failures=0).
  • Non-goals: Does not alter executable control-plane or provider runtime semantics.

该 PR 收口 #9072 遗留的文档与注释截断问题:若不补齐英文阅读指南的独立记录规则、Dev Book 不变式粗体小标题及非授权声明,并在发布 smoke 中固化校验,后续编辑仍会静默丢失同类结构信息。

改动思路

整体遵循最小可逆的文本收口与 smoke 加固思路:Bounded follow-up cleanup restoring dropped definitions, non-authority boundaries, Dev Book invariant/ordinal titles, and comment punctuation from #9072 while adding structural checks in dev-book-publication-smoke.py.。边界约束:Limited strictly to docs, comment-only cleanup in touched TS/Python files (no AST/runtime behavior changes), dev-book-publication-smoke.py, and test_dev_book_reader_checkpoints.py.。

第一,补齐 loopx/capabilities/*、docs/development/* 及 Dev Book 中英文章节中被误删的正向定义、非授权声明、指代主语和序数标题;第二,在 examples/dev-book-publication-smoke.py 与 tests/test_dev_book_reader_checkpoints.py 增加连续编号和标题非空校验,并与基准 2b6dfe0a70 做对照;第三,清理 TypeScript/Python 注释和 docstring 中的残余分号与孤立换行,不改变任何可执行逻辑。

具体改动

  1. 文档与 Dev Book 结构修复:恢复 docs/book/en/chapters/00-reading-guide.md 中“预览、执行、读回和测试结果分别记录”的英文对应规则,以及 01-from-session-to-loop.md、04b-budget-and-admission.md、06-codex-app.md、08-extension-placement.md、09-extension-scaffold.md、core-state-machines.md、source-protocol-map.md、source-trace-protocol-chain.md、source-validation-to-pr.md 的 ## Invariants 与 Cost/Boundary/Failure 粗体小标题;同步补全 loopx/capabilities/* 与 docs/development/* 中的完整定义与非授权边界描述。
  2. 回归门禁增强:examples/dev-book-publication-smoke.py 新增 assert_chapter_invariants_and_sequences() 与阅读指南双语对齐条目,tests/test_dev_book_reader_checkpoints.py 增补对应章节不变量测试(20 passed, 336 subtests)。
  3. 源码注释清理:修正 loopx/control_plane/collaboration/conversation_binding.ts、source_grants.ts、refresh_recovery.ts、receipt_log_snapshot.ts、task_lease_eligibility.ts、antigravity_adapter.py、steward_managed_mode.py、private_ingress.py、openai_policy.ts、workspace-progressive-status.ts 的注释标点与换行格式,经 diff 核对仅涉及注释字符。

对主干的风险

对主干行为风险极低。全部 TypeScript 与 Python 代码改动均严格限于注释与 docstring 格式清理,未触及控制面判断、持久化状态、权限或运行时路径。唯一新增约束来自 dev-book-publication-smoke.py 对 ## Invariants 与序数小标题连续性的检查,旨在及早阻断同类文档结构退化。

我的整体评价

本次 #9072 尾项收口范围干净、目标明确,中英文文档、注释与结构化回归测试保持一致。本地已实测通过 examples/dev-book-publication-smoke.py、examples/capability-extension-placement-doc-smoke.py、tests/test_dev_book_reader_checkpoints.py(20 passed, 336 subtests)、tests/control_plane_ts/conversation_binding.test.ts 与 loopx canary premerge --tier quick(4/4 canaries + public_boundary 通过,0 failures)。架构边界评估:Limited strictly to docs, comment-only cleanup in touched TS/Python files (no AST/runtime behavior changes), dev-book-publication-smoke.py, and test_dev_book_reader_checkpoints.py. 原因:Bounded follow-up cleanup restoring dropped definitions, non-authority boundaries, Dev Book invariant/ordinal titles, and comment punctuation from #9072 while adding structural checks in dev-book-publication-smoke.py.。视觉评审结论:Only a comment/whitespace cleanup in workspace-progressive-status.ts with zero rendered UI or layout changes. 未验证范围:none。

English Verdict: APPROVE

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant